feat: add version constraint validation for atmos.yaml #1759
Conversation
Add comprehensive Product Requirement Document for semantic version constraint validation feature. Allows atmos.yaml configurations to specify required Atmos version ranges using hashicorp/go-version library with configurable enforcement levels (fatal, warn, silent). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Dependency Review✅ No vulnerabilities or license issues found.Scanned FilesNone |
📝 WalkthroughWalkthroughAdds Atmos version-constraint validation: new VersionConstraint model and constraint parsing/validation using hashicorp/go-version; sentinel errors; CLI bootstrap integration with environment override (ATMOS_VERSION_ENFORCEMENT); a constraint-aware release listing mode; schema updates; unit tests; and documentation and blog pages. Changes
Sequence Diagram(s)sequenceDiagram
participant User as CLI (user)
participant Config as Config Loader
participant Env as Env (ATMOS_VERSION_ENFORCEMENT)
participant Validator as Version Validator
participant Releases as Release Lister
User->>Config: start / load atmos.yaml
Config->>Validator: extract version.constraint
Env->>Validator: provide enforcement override (if set)
Validator->>Validator: parse constraint (hashicorp/go-version)
alt parse error
Validator-->>User: ErrInvalidVersionConstraint (error)
else parsed
Validator->>Validator: compare with current Atmos version
alt satisfied
Validator-->>User: continue
else violated
alt enforcement == fatal
Validator-->>User: ErrVersionConstraint (fatal)
else enforcement == warn
Validator-->>User: emit warning (continue)
else enforcement == silent
Validator-->>User: continue silently
end
end
end
Note over User,Releases: When using --constraint-aware
User->>Releases: fetch releases
Releases->>Validator: apply constraint to filter releases
Releases-->>User: filtered list
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Possibly related PRs
Suggested labels
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/prd/version-constraint.md (2)
108-115: Add language identifiers to code/output blocks for clarity.Several fenced code blocks lack language specifiers. For error/warning message blocks (lines 108–115, 129–135, 503–512, 515–523, 526–532), use
```textto properly render. Line 536–552 is a diagram/flow, which could use```textas well. This improves IDE syntax highlighting and markdown linting compliance.Examples:
- ``` + ```text ✗ Atmos version constraint not satisfied ...Also applies to: 129-135, 503-532, 536-552
208-208: Convert bare URL to markdown link.Line 208 has a bare URL. Convert it to a proper markdown link:
- Full syntax: https://github.com/hashicorp/go-version + Full syntax: [hashicorp/go-version](https://github.com/hashicorp/go-version)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/prd/version-constraint.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:206-206
Timestamp: 2025-01-17T00:18:57.769Z
Learning: For indirect dependencies with license compliance issues in the cloudposse/atmos repository, the team prefers to handle them in follow-up PRs rather than blocking the current changes, as these issues often require deeper investigation of the dependency tree.
Learnt from: osterman
Repo: cloudposse/atmos PR: 801
File: examples/quick-start-advanced/Dockerfile:9-9
Timestamp: 2024-11-23T00:13:22.004Z
Learning: When updating the `ATMOS_VERSION` in Dockerfiles, the team prefers to pin to the next future version when the PR merges, even if the version is not yet released.
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.
📚 Learning: 2025-07-05T20:59:02.914Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
Applied to files:
docs/prd/version-constraint.md
📚 Learning: 2024-12-02T21:26:32.337Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 808
File: pkg/config/config.go:478-483
Timestamp: 2024-12-02T21:26:32.337Z
Learning: In the 'atmos' project, when reviewing Go code like `pkg/config/config.go`, avoid suggesting file size checks after downloading remote configs if such checks aren't implemented elsewhere in the codebase.
Applied to files:
docs/prd/version-constraint.md
🪛 LanguageTool
docs/prd/version-constraint.md
[grammar] ~11-~11: Use a hyphen to join words.
Context: ...State Currently, Atmos provides version checking functionality under the `versio...
(QB_NEW_EN_HYPHEN)
[typographical] ~233-~233: Consider using a typographic close quote here.
Context: ...ementinatmos.yaml3. Default value"fatal"` (lowest) ## Implementation Plan...
(EN_QUOTES)
[typographical] ~568-~568: Consider using typographic quotation marks here.
Context: ...rsion.constraint.require` is treated as "no constraint" - Default enforcement is "fatal" for sa...
(EN_QUOTES)
[typographical] ~569-~569: Consider using typographic quotation marks here.
Context: ...no constraint" - Default enforcement is "fatal" for safety, but can be explicitly set t...
(EN_QUOTES)
[typographical] ~569-~569: Consider using typographic quotation marks here.
Context: ...or safety, but can be explicitly set to "warn" ## Security Considerations - Version ...
(EN_QUOTES)
🪛 markdownlint-cli2 (0.18.1)
docs/prd/version-constraint.md
108-108: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
129-129: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
208-208: Bare URL used
(MD034, no-bare-urls)
503-503: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
515-515: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
526-526: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
536-536: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
619-619: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: Build (macos)
- GitHub Check: Build (windows)
- GitHub Check: Run pre-commit hooks
- GitHub Check: Analyze (go)
- GitHub Check: Lint (golangci)
- GitHub Check: Review Dependency Licenses
- GitHub Check: autofix
- GitHub Check: Summary
🔇 Additional comments (2)
docs/prd/version-constraint.md (2)
1-100: Excellent PRD—clear problem, solid design, and thorough planning.This is a well-structured requirements document. The problem statement is articulate, the design decisions are justified (especially the choice of string format and hashicorp/go-version reuse), and the 7 configuration examples cover realistic scenarios. The implementation plan is detailed enough to guide development, and the backward-compatibility guarantee is reassuring.
100-250: Validate environment override precedence against Atmos conventions.The
ATMOS_VERSION_ENFORCEMENToverride precedence (env var > config > default) is sensible, but it's worth verifying this pattern aligns with how Atmos handles other environment-based configuration overrides elsewhere in the codebase to keep behavior predictable.
…on list concerns Add comprehensive problem statements addressing real-world challenges: - Multi-environment version drift (CI, local, containers) - Silent feature unavailability in older versions - Experimentation friction without proper warnings Add new configuration examples: - Multi-environment consistency enforcement - Experimentation mode with warnings for unsupported versions Add Phase 3 proposal for constraint-aware version listing: - Optional --constraint-aware flag for atmos version list - Filters releases based on version.constraint.require - Three design options with recommendation for flag-based approach - Future enhancement: warnings for versions outside constraints 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
docs/prd/version-constraint.md (7)
3-33: Excellent problem framing—clear motivation for the feature.The problem statement does a strong job articulating real challenges teams face (multi-environment drift, feature gating, breaking changes). The existing
version.checkcontext helps orient readers to what's already available.Minor: Line 11 grammar—consider hyphenating: "version-checking functionality" per the static analysis flag.
100-228: Comprehensive and realistic examples.The nine examples effectively demonstrate the feature's flexibility, progressing naturally from simple minimum-version constraints through multi-constraint scenarios and experimentation modes. The multi-line custom messages in Examples 6, 7, and 8 show practical team adoption patterns.
Minor formatting: Lines 111 and 132 (error output examples) lack language tags—add
bash ortext to comply with MD040.
230-271: Clear reference and sensible override hierarchy.The syntax table covers all supported operators, and the precedence order for enforcement (env var > config > default) is both sensible and well-explained. Good thought on allowing runtime overrides for CI/debugging scenarios.
Line 246: Wrap the bare URL in markdown link syntax—
[go-version](https://github.com/hashicorp/go-version)per MD034.
273-561: Implementation plan is detailed, phased, and realistic.Phase 1 provides concrete file locations, Go code patterns, and test cases. The validation logic properly handles enforcement levels and error cases. Phase 2 scope is appropriately scoped to documentation. Phase 3 thoughtfully analyzes design options before recommending the flag-based approach.
The ValidateConstraint function and integration in initConfig are straightforward. Test coverage examples show good edge-case thinking (empty constraints, ranges, pessimistic constraints, invalid syntax).
Formatting: Add
golanguage tags to code blocks (lines 280–290, 294–321, 325–426, 430–500) for syntax highlighting consistency—though this is minor and won't affect implementation.
663-715: User-facing messaging is clear and helpful.Error messages include visual indicators, structured data (Required/Current versions), and actionable next steps (upgrade link, support contact). The validation flow diagram clearly shows the decision tree including early exit for invalid syntax constraints.
Formatting: Lines 666, 678, 689, 699 (error message blocks) should specify language—
bashortext—for syntax highlighting.
717-820: Thorough coverage of non-functional concerns and design rationale.Testing strategy has clear coverage target. Security and performance sections appropriately address offline-safety and minimal overhead. The dependencies section convincingly argues for reusing
hashicorp/go-version(already present, Terraform-compatible, zero new dependencies).The design rationale comparing string vs. list format is particularly well-articulated and includes library evidence showing native comma-separated parsing support.
Formatting: Lines 631, 637, 643, 782 use emphasis (Option 1, Option 2, etc.) instead of markdown headings. Consider converting to
### Option 1: Flag-based (RECOMMENDED)format for better semantic structure per MD036.Static analysis also flagged typographical quote suggestions in several places (straight quotes vs. smart quotes). While minor and often a matter of style, consider standardizing if the project has a quote convention.
1-820: Comprehensive, well-reasoned PRD ready for implementation planning.This PRD effectively specifies a version constraint validation feature that addresses real operational challenges. The design is conservative (fully backward-compatible, reuses existing dependency), the examples are practical, and the three-phase implementation plan is realistic. The feature elegantly extends the existing
versionconfig without breaking changes.Strong aspects:
- Solid design choices: String format constraints match Terraform semantics and leverage library native support
- Enforcement hierarchy (fatal → warn → silent) provides appropriate flexibility
- Environment variable override enables debugging without config changes
- Comprehensive examples from minimum versions to multi-environment consistency
- Phased approach defers optional enhancements (Phase 3) appropriately
Minor observations for "Chill" mode (all optional):
- Markdown linting: Add language tags to code blocks (lines 111, 132, 280–290, 294–321, 325–426, 430–500, 666, 678, 689, 699)
- Markdown structure: Convert emphasis-styled options to
### Headingformat for better semantics- Bare URL: Wrap line 246 URL in markdown link syntax
- Grammar: Line 11 — consider hyphenating "version-checking"
- Quotes: Various lines use straight quotes; if the project standardizes on smart quotes, apply consistently
Ready to implement Phase 1 core validation and integration.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/prd/version-constraint.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:206-206
Timestamp: 2025-01-17T00:18:57.769Z
Learning: For indirect dependencies with license compliance issues in the cloudposse/atmos repository, the team prefers to handle them in follow-up PRs rather than blocking the current changes, as these issues often require deeper investigation of the dependency tree.
Learnt from: osterman
Repo: cloudposse/atmos PR: 801
File: examples/quick-start-advanced/Dockerfile:9-9
Timestamp: 2024-11-23T00:13:22.004Z
Learning: When updating the `ATMOS_VERSION` in Dockerfiles, the team prefers to pin to the next future version when the PR merges, even if the version is not yet released.
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.
📚 Learning: 2025-09-13T16:39:20.007Z
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: cmd/markdown/atmos_toolchain_aliases.md:2-4
Timestamp: 2025-09-13T16:39:20.007Z
Learning: In the cloudposse/atmos repository, CLI documentation files in cmd/markdown/ follow a specific format that uses " $ atmos command" (with leading space and dollar sign prompt) in code blocks. This is the established project convention and should not be changed to comply with standard markdownlint rules MD040 and MD014.
Applied to files:
docs/prd/version-constraint.md
📚 Learning: 2025-07-05T20:59:02.914Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
Applied to files:
docs/prd/version-constraint.md
🪛 LanguageTool
docs/prd/version-constraint.md
[grammar] ~11-~11: Use a hyphen to join words.
Context: ...State Currently, Atmos provides version checking functionality under the `versio...
(QB_NEW_EN_HYPHEN)
[typographical] ~271-~271: Consider using a typographic close quote here.
Context: ...ementinatmos.yaml3. Default value"fatal"` (lowest) ## Implementation Plan...
(EN_QUOTES)
[typographical] ~641-~641: Consider using typographic quotation marks here.
Context: ... Con: Confusing if constraint is set to "warn" enforcement **Option 3: Auto-enable wh...
(EN_QUOTES)
[typographical] ~643-~643: Consider using typographic quotation marks here.
Context: ...o-enable when constraint enforcement is "fatal"** - Pro: Smart default based on enforce...
(EN_QUOTES)
[typographical] ~731-~731: Consider using typographic quotation marks here.
Context: ...rsion.constraint.require` is treated as "no constraint" - Default enforcement is "fatal" for sa...
(EN_QUOTES)
[typographical] ~732-~732: Consider using typographic quotation marks here.
Context: ...no constraint" - Default enforcement is "fatal" for safety, but can be explicitly set t...
(EN_QUOTES)
[typographical] ~732-~732: Consider using typographic quotation marks here.
Context: ...or safety, but can be explicitly set to "warn" ## Security Considerations - Version ...
(EN_QUOTES)
🪛 markdownlint-cli2 (0.18.1)
docs/prd/version-constraint.md
111-111: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
132-132: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
246-246: Bare URL used
(MD034, no-bare-urls)
631-631: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
637-637: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
643-643: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
666-666: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
678-678: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
689-689: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
699-699: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
782-782: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: Build (windows)
- GitHub Check: Build (macos)
- GitHub Check: Analyze (go)
- GitHub Check: Lint (golangci)
- GitHub Check: autofix
- GitHub Check: Run pre-commit hooks
- GitHub Check: Review Dependency Licenses
- GitHub Check: Summary
🔇 Additional comments (1)
docs/prd/version-constraint.md (1)
35-96: Well-designed data model with strong rationale.The YAML structure is clean, the Go struct properly tagged, and the design choice for string-format constraints (vs. list) is justified convincingly (Terraform parity, library native support, simpler YAML). The comment examples in the struct definition are particularly helpful.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1759 +/- ##
==========================================
+ Coverage 72.18% 72.20% +0.01%
==========================================
Files 475 476 +1
Lines 45740 45800 +60
==========================================
+ Hits 33017 33069 +52
- Misses 10099 10107 +8
Partials 2624 2624
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
osterman
added
the
no-release
Add ability to enforce Atmos version requirements in atmos.yaml configuration. Teams can now ensure consistent Atmos versions across developers and CI/CD. Configuration: - version.constraint.require: semver constraint (e.g., ">=1.100.0, <2.0.0") - version.constraint.enforcement: fatal|warn|silent (default: fatal) - version.constraint.message: custom error message - ATMOS_VERSION_ENFORCEMENT env var override Uses hashicorp/go-version library (already in go.mod) for Terraform-compatible constraint syntax including pessimistic operator (~>). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
github-actions
bot
added
size/xl
|
Warning This PR exceeds the recommended limit of 1,000 lines.Large PRs are difficult to review and may be rejected due to their size. Please verify that this PR does not address multiple issues. |
Regenerate snapshot to reflect intentional changes from version constraint feature: - Lowercase JSON field names (added explicit json tags) - Empty objects for zero-value structs (omitempty behavior) - New constraint field in version config 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
osterman
changed the title
Resolve merge conflict in configuration.mdx by keeping main's simplified structure while adding version constraints to See Also. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Move version configuration documentation into version/ subdirectory following the established pattern used by settings/, auth/, etc. Structure: - version/version.mdx - Index page with overview - version/check.mdx - Version checking (moved from version.mdx) - version/constraint.mdx - Version constraints (moved from version-constraints.mdx) URL changes: - /cli/configuration/version - Now serves index page - /cli/configuration/version/check - Version checking docs - /cli/configuration/version/constraint - Version constraint docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Brings in recent changes from main including: - Native devcontainer support (#1697) - Version constraint validation for atmos.yaml (#1759) - Fix for empty backend.tf.json generation (#1833) - Document missing component metadata fields (#1840) Resolved conflicts: - cmd/root.go: Added both devcontainer and init/scaffold imports - Test snapshot will be regenerated to include devcontainer command Note: Pre-existing linting issues in init/scaffold experimental code remain and will be addressed before merging to main. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Summary
Add ability to enforce Atmos version requirements in
atmos.yamlconfiguration. Teams can now ensure consistent Atmos versions across developers and CI/CD pipelines.What's Included
Core Implementation
hashicorp/go-versionlibrary (already in go.mod)fatal(exit),warn(continue),silent(skip)ATMOS_VERSION_ENFORCEMENT)Configuration
Files Changed
pkg/schema/version.go- Schema structs with JSON/YAML tagspkg/version/constraint.go- Constraint parsing and validationpkg/config/utils.go- Integration with config loadingerrors/errors.go- Error definitions*_test.gofilesDocumentation
website/docs/cli/configuration/version-constraints.mdx- Full user guidewebsite/docs/cli/configuration/configuration.mdx- Configuration reference updatewebsite/blog/2025-12-01-version-constraint-validation.mdx- Release blog postdocs/prd/version-constraint.md- Product requirements documentKey Features
>=2.5.0,<3.0.0, ranges, pessimistic (~>2.5), exclusions (!=2.7.0)hashicorp/go-versionv1.7.0🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.